.TH PBMTOJBG 1 "2014-08-22"
.SH NAME
pbmtojbg \- portable bitmap to JBIG1 file converter
.SH SYNOPSIS
.B pbmtojbg
[
.I options
]
[
.I input-file
| \-  [
.I output-file
]]
.br
.SH DESCRIPTION
Reads a file in portable bitmap (PBM) format, compresses it,
and outputs the image as a
.I JBIG1
bi-level image entity (BIE).

.I JBIG1
is a highly effective, lossless compression algorithm for
bi-level images (one bit per pixel), which is particularly suitable
for scanned document pages.

A
.I JBIG1
encoded image can be stored in several resolution layers (progressive mode).
This allows the decoder to recover a lower-resolution version of the
encoded image without having to read the complete file.
These resolution layers can be stored all in one single BIE or they
can be stored in several separate BIE files.
All resolution layers, except the lowest one, are stored merely as
differences to the next lower resolution layer. This requires less
space than encoding the full image completely every time. Each resolution
layer has twice the number of horizontal and vertical pixels than
the next lower layer.

For best speed and compression, if you are not interested in
efficiently extracting lower-resolution versions from the compressed
file, use sequential mode (single resolution layer, option
.BR \-q ).

.I JBIG1
files can also store several bits per pixel, as separate bitmap planes,
and
.I pbmtojbg
can read a portable graymap format (PGM) file and transform it into
a multi-plane BIE.

.SH OPTIONS
.TP 12
.BI \-
A single hyphen instead of an input file name causes
.I pbmtojbg
to read the data from standard input instead of from a file.
.TP
.BI \-v
List technical details of the created file (verbose mode).
.TP
.BI \-f
This option makes the output file comply with the \[lq]facsimile application
profile\[rq] defined in ITU-T Recommendation T.85. It is a shortcut for
.BR "-q -o 0 -p 8 -s 128 -t 1 -m 127" .
.TP
.BI \-C " string"
Add the
.I string
in a comment marker segment to the produced data stream.
.br
(There is no support at present for adding comments that contain a
zero byte.)
.P
Options affecting the number of resolution layers produced:
.TP 12
.BI \-q
Encode the image in one single resolution layer (sequential mode), which
is usually the most efficient compression method. By default, the number
of resolution layers is instead chosen automatically such that the lowest layer
image is not larger than 640 \(mu 480 pixels.
This option is just a shortcut for
.BR "-d 0" .
.TP
.BI \-x " number"
Specify the maximal horizontal size of the lowest resolution layer.
Default: 640 pixels
.TP
.BI \-y " number"
Specify the maximal vertical size of the lowest resolution layer.
Default: 480 pixels
.TP
.BI \-d " number"
Specify the total number of differential resolution layers into which to split
the input image (in addition to the lowest layer). Each additional
layer reduces both the width and height of layer 0 by 50%.
This option overrides options
.B \-x
and
.BR \-y ,
which are usually a more convenient way of selecting the number of
resolution layers.
.TP
.BI \-l " number"
Select the lowest resolution layer
.I D\s-2\dL\u\s0
that will appear in the generated
BIE.
.I JBIG1
can store the various resolution layers of an image in progressive mode
split across several BIEs. Options
.B \-l
and
.B \-h
allow you to select the resolution-layer interval that will appear
in the created BIE. The lowest resolution layer has number 0 and
this is also the default value. The default is to write all layers.
.TP
.BI \-h " number"
Select the highest resolution layer
.I D
that will appear in the generated BIE. The default is to write all layers.
See also option
.BR \-l .
.P
Options for changing other parameters indicated in the BIE header:
.TP 12
.BI \-s " number"
The
.I JBIG1
algorithm splits each image into horizontal stripes. This
option specifies
.IR L\s-2\d0\u\s0 ,
the layer-0 height of each such stripe (except for the last one,
which can be shorter).
The default is to split the whole image into approximately 35 stripes.
.TP
.BI \-m " number"
Select the maximum horizontal offset
.I M\s-2\dX\u\s0
of the adaptive template pixel.
The
.I JBIG1
encoder uses ten neighbour pixels to estimate the probability of the
next pixel being black or white. It can adjust the location of one
of these ten context pixels.
This is especially useful for dithered images, as long as the
distance of this adaptive pixel can be adjusted to the period of the
dither pattern. By default, the adaptive template pixel is allowed to
move up to 8 pixels away horizontally. This encoder supports distances
up to 127 pixels.
.br
Annex A of the standard suggests that decoders should support at least
a horizontal distance of 16 pixels, so using values not higher than 16
for
.I number
might increase the chances of interoperability with other
.I JBIG1
implementations. On the other hand, the T.85 fax application profile
requires decoders to support horizontal offsets up to 127 pixels,
which is the maximum value permitted by the standard. (The maximal
vertical offset
.I M\s-2\dY\u\s0
of the adaptive template pixel is always zero for this
encoder.)
.TP
.BI \-o " number"
Specify the order in which image data appears in the output.
.I JBIG1
separates an image into several horizontal stripes, resolution layers
and planes, were each plane contains one bit per pixel. One single
stripe in one plane and layer is encoded as a data unit called stripe
data entity (SDE) inside the BIE. There are 12 different possible
orders in which the SDEs can be stored inside the BIE and
.I number
selects which one shall be used. For receiving applications, the order of
the SDEs mainly matters if they want to start decoding an image before
it has been received completely.
For instance, some applications may prefer that the outermost of the
three loops (stripes, layers, planes) is over all layers so that all
data of the lowest resolution layer is transmitted first.
.br
The following values for
.I number
select these loop arrangements for writing the SDEs (outermost
loop first):

   0  	planes, layers, stripes
.br
   2  	layers, planes, stripes
.br
   3  	layers, stripes, planes
.br
   4  	stripes, planes, layers
.br
   5  	planes, stripes, layers
.br
   6  	stripes, layers, planes

All loops count starting with zero, however by adding 8 to the above
order code, the layer loop can be reversed so that it counts down to zero
and then higher resolution layers will be stored before lower layers.
The default order is 3, which writes at first all planes of the first
stripe and then completes layer 0 before continuing with the next
layer, and so on.
.TP
.BI \-p " number"
This option activates or deactivates various optional algorithms
defined in the
.I JBIG1
standard. Just add the numbers of the following options which you want to
activate in
order to get the
.I number
value:

   4 	deterministic prediction (DPON)
.br
   8 	layer 0 typical prediction (TPBON)
.br
  16 	diff. layer typ. pred. (TPDON)
.br
  64 	layer 0 two-line template (LRLTWO)

This option is only for specialist applications (e.g., communication with
.I JBIG1
subset implementations, debugging). The default is 28, which usually
provides the best compression result.
.P
Options affecting the processing of PGM files:
.TP 12
.BI \-b
Use binary values instead of Gray code words in order to encode pixel
values in multiple bit planes. This option has only an effect if the
input is a PGM file and if more than one plane is produced. Note that
the decoder has to make the same choice, but the BIE does not
indicate whether Gray or binary code words were used by the encoder.
.TP
.BI \-t " number"
Encode only the specified number of most significant bit planes. This
option reduces the depth of an input PGM file if not all
bits per pixel are needed in the output.
.P
Options to help generating test files:
.TP 12
.BI \-r
Use the SDRST marker instead of the normal SDNORM marker. The probably
only useful application for this option is to generate test data for
checking whether a
.I JBIG1
decoder has implemented SDRST correctly. In a normal
.I JBIG1
data stream, each stripe data entity (SDE) is terminated by an SDNORM
marker, which preserves the state of the arithmetic encoder (and more)
for the next stripe in the same layer. The alternative SDRST marker
resets this state at the end of the stripe.
.TP
.BI \-Y " number"
Specify a preliminary image height
.IR Y\s-2\dD\u\s0 .
A long time ago, there were fax
machines that couldn't even hold a single page in memory. They had to
start transmitting data before the page was scanned in completely and
before even the height of the resulting image was known.
The authors of the standard added a rather ugly hack to JBIG1
to support this use case. The NEWLEN marker segment can
override the image height stated in the BIE header anywhere later in
the data stream. Normally
.I pbmtojbg
never generates NEWLEN marker segments, as it knows the correct image
height when it outputs the header. This option is solely intended for
the purpose of generating test files with NEWLEN marker segments. It
can be used to specify a higher initial image height for use in the
BIE header, and
.I pbmtojbg
will then add a NEWLEN marker segment at the latest possible
opportunity to the data stream to signal the correct final height.
It will also set the VLENGTH flag in the BIE header.
.TP
.BI \-c
Determine the adaptive template pixel movement as suggested in Annex C
of the standard. By default the template change takes place directly
in the next line, which is most effective. However, a few conformance
test examples in the standard require the adaptive template change to
be delayed until the first line of the next stripe. This option
selects this special behavior, which is normally not useful other than
for conformance testing.
.SH BUGS
Using standard input and standard output for binary data works only on
systems where there is no difference between binary and text streams
(e.g., Unix). On other systems (e.g., MS-DOS), using standard input or
standard output may cause control characters like CR or LF to be
inserted or deleted and this will damage the binary data.
.SH STANDARDS
This program implements the
.I JBIG1
image coding algorithm as specified in international standard ISO/IEC
11544:1993 and ITU-T Recommendation T.82(1993).
.SH AUTHOR
Markus Kuhn wrote
.UR http://www.cl.cam.ac.uk/~mgk25/jbigkit/
.I JBIG-KIT
.UE ,
which includes
.IR pbmtojbg .
.SH SEE ALSO
pbm(5), pgm(5), jbgtopbm(1)
